<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Filter_Inflector - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.filter.inflector.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.filter.inflector.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.filter.input.html">Zend_Filter_Input</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.filter.html">Zend_Filter</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.form.html">Zend_Form</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.filter.inflector" class="section"><div class="info"><h1 class="title">Zend_Filter_Inflector</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Filter_Inflector</span> is a general purpose tool for
        rules-based inflection of strings to a given target.
    </p>

    <p class="para">
        As an example, you may find you need to transform MixedCase or camelCasedWords into a
        path; for readability, OS policies, or other reasons, you also need to
        lower case this, and you want to separate the words using a dash (&#039;-&#039;).
        An inflector can do this for you.
    </p>

    <p class="para">
        <span class="classname">Zend_Filter_Inflector</span> implements
        <span class="classname">Zend_Filter_Interface</span>; you perform inflection by calling
         <span class="methodname">filter()</span> on the object instance.
    </p>

    <div class="example" id="zend.filter.inflector.camel_case_example"><div class="info"><p><b>Example #1 Transforming MixedCase and camelCaseText to another format</b></p></div>
        

        <pre class="programlisting brush: php">
$inflector = new Zend_Filter_Inflector(&#039;pages/:page.:suffix&#039;);
$inflector-&gt;setRules(array(
    &#039;:page&#039;  =&gt; array(&#039;Word_CamelCaseToDash&#039;, &#039;StringToLower&#039;),
    &#039;suffix&#039; =&gt; &#039;html&#039;
));

$string   = &#039;camelCasedWords&#039;;
$filtered = $inflector-&gt;filter(array(&#039;page&#039; =&gt; $string));
// pages/camel-cased-words.html

$string   = &#039;this_is_not_camel_cased&#039;;
$filtered = $inflector-&gt;filter(array(&#039;page&#039; =&gt; $string));
// pages/this_is_not_camel_cased.html
</pre>

    </div>

    <div class="section" id="zend.filter.inflector.operation"><div class="info"><h1 class="title">Operation</h1></div>
        

        <p class="para">
            An inflector requires a <em class="emphasis">target</em> and one or more
            <em class="emphasis">rules</em>. A target is basically a string that
            defines placeholders for variables you wish to substitute. These are
            specified by prefixing with a &#039;:&#039;: <em class="emphasis">:script</em>.
        </p>

        <p class="para">
            When calling  <span class="methodname">filter()</span>, you then pass in an array of
            key and value pairs corresponding to the variables in the target.
        </p>

        <p class="para">
            Each variable in the target can have zero or more rules associated
            with them. Rules may be either <em class="emphasis">static</em> or refer to a
            <span class="classname">Zend_Filter</span> class. Static rules will replace with the
            text provided. Otherwise, a class matching the rule provided will be
            used to inflect the text. Classes are typically specified using a
            short name indicating the filter name stripped of any common prefix.
        </p>

        <p class="para">
            As an example, you can use any <span class="classname">Zend_Filter</span> concrete
            implementations; however, instead of referring to them as
            &#039;<span class="classname">Zend_Filter_Alpha</span>&#039; or
            &#039;<span class="classname">Zend_Filter_StringToLower</span>&#039;, you&#039;d specify
            only &#039;<span class="classname">Alpha</span>&#039; or &#039;<span class="classname">StringToLower</span>&#039;.
        </p>
    </div>

     <div class="section" id="zend.filter.inflector.paths"><div class="info"><h1 class="title">Setting Paths To Alternate Filters</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Filter_Inflector</span> uses
            <span class="classname">Zend_Loader_PluginLoader</span> to manage loading filters to
            use with inflection. By default, any filter prefixed with
            <span class="classname">Zend_Filter</span> will be available. To access filters with
            that prefix but which occur deeper in the hierarchy, such as the
            various Word filters, simply strip off the <span class="classname">Zend_Filter</span> prefix:
        </p>

        <pre class="programlisting brush: php">
// use Zend_Filter_Word_CamelCaseToDash as a rule
$inflector-&gt;addRules(array(&#039;script&#039; =&gt; &#039;Word_CamelCaseToDash&#039;));
</pre>


        <p class="para">
            To set alternate paths, <span class="classname">Zend_Filter_Inflector</span> has a
            utility method that proxies to the plugin loader,
             <span class="methodname">addFilterPrefixPath()</span>:
        </p>

        <pre class="programlisting brush: php">
$inflector-&gt;addFilterPrefixPath(&#039;My_Filter&#039;, &#039;My/Filter/&#039;);
</pre>


        <p class="para">
            Alternatively, you can retrieve the plugin loader from the
            inflector, and interact with it directly:
        </p>

        <pre class="programlisting brush: php">
$loader = $inflector-&gt;getPluginLoader();
$loader-&gt;addPrefixPath(&#039;My_Filter&#039;, &#039;My/Filter/&#039;);
</pre>


        <p class="para">
            For more options on modifying the paths to filters, please see <a href="zend.loader.pluginloader.html" class="link">the PluginLoader
                documentation</a>.
        </p>
    </div>

    <div class="section" id="zend.filter.inflector.targets"><div class="info"><h1 class="title">Setting the Inflector Target</h1></div>
        

        <p class="para">
            The inflector target is a string with some placeholders for
            variables. Placeholders take the form of an identifier, a colon
            (&#039;:&#039;) by default, followed by a variable name: &#039;:script&#039;, &#039;:path&#039;,
            etc. The  <span class="methodname">filter()</span> method looks for the identifier
            followed by the variable name being replaced.
        </p>

        <p class="para">
            You can change the identifier using the
             <span class="methodname">setTargetReplacementIdentifier()</span> method, or passing it
            as the third argument to the constructor:
        </p>

        <pre class="programlisting brush: php">
// Via constructor:
$inflector = new Zend_Filter_Inflector(&#039;#foo/#bar.#sfx&#039;, null, &#039;#&#039;);

// Via accessor:
$inflector-&gt;setTargetReplacementIdentifier(&#039;#&#039;);
</pre>


        <p class="para">
            Typically, you will set the target via the constructor. However, you
            may want to re-set the target later (for instance, to modify the
            default inflector in core components, such as the
            <span class="classname">ViewRenderer</span> or <span class="classname">Zend_Layout</span>).
             <span class="methodname">setTarget()</span> can be used for this purpose:
        </p>

        <pre class="programlisting brush: php">
$inflector = $layout-&gt;getInflector();
$inflector-&gt;setTarget(&#039;layouts/:script.phtml&#039;);
</pre>


        <p class="para">
            Additionally, you may wish to have a class member for your class
            that you can use to keep the inflector target updated -- without
            needing to directly update the target each time (thus saving on
            method calls).  <span class="methodname">setTargetReference()</span> allows you to do
            this:
        </p>

        <pre class="programlisting brush: php">
class Foo
{
    /**
     * @var string Inflector target
     */
    protected $_target = &#039;foo/:bar/:baz.:suffix&#039;;

    /**
     * Constructor
     * @return void
     */
    public function __construct()
    {
        $this-&gt;_inflector = new Zend_Filter_Inflector();
        $this-&gt;_inflector-&gt;setTargetReference($this-&gt;_target);
    }

    /**
     * Set target; updates target in inflector
     *
     * @param  string $target
     * @return Foo
     */
    public function setTarget($target)
    {
        $this-&gt;_target = $target;
        return $this;
    }
}
</pre>

    </div>

    <div class="section" id="zend.filter.inflector.rules"><div class="info"><h1 class="title">Inflection Rules</h1></div>
        

        <p class="para">
            As mentioned in the introduction, there are two types of rules:
            static and filter-based.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                It is important to note that regardless of the method in which you add
                rules to the inflector, either one-by-one, or all-at-once; the order is very
                important. More specific names, or names that might contain other rule names,
                must be added before least specific names. For example, assuming the two rule
                names &#039;moduleDir&#039; and &#039;module&#039;, the &#039;moduleDir&#039; rule should appear before module
                since &#039;module&#039; is contained within &#039;moduleDir&#039;. If &#039;module&#039; were added before
                &#039;moduleDir&#039;, &#039;module&#039; will match part of &#039;moduleDir&#039; and process it leaving &#039;Dir&#039;
                inside of the target uninflected.
            </p>
        </p></blockquote>

        <div class="section" id="zend.filter.inflector.rules.static"><div class="info"><h1 class="title">Static Rules</h1></div>
            

            <p class="para">
                Static rules do simple string substitution; use them when you
                have a segment in the target that will typically be static, but
                which you want to allow the developer to modify. Use the
                 <span class="methodname">setStaticRule()</span> method to set or modify the rule:
            </p>

            <pre class="programlisting brush: php">
$inflector = new Zend_Filter_Inflector(&#039;:script.:suffix&#039;);
$inflector-&gt;setStaticRule(&#039;suffix&#039;, &#039;phtml&#039;);

// change it later:
$inflector-&gt;setStaticRule(&#039;suffix&#039;, &#039;php&#039;);
</pre>


            <p class="para">
                Much like the target itself, you can also bind a static rule to
                a reference, allowing you to update a single variable instead of
                require a method call; this is often useful when your class uses
                an inflector internally, and you don&#039;t want your users to need
                to fetch the inflector in order to update it. The
                 <span class="methodname">setStaticRuleReference()</span> method is used to
                accomplish this:
            </p>

            <pre class="programlisting brush: php">
class Foo
{
    /**
     * @var string Suffix
     */
    protected $_suffix = &#039;phtml&#039;;

    /**
     * Constructor
     * @return void
     */
    public function __construct()
    {
        $this-&gt;_inflector = new Zend_Filter_Inflector(&#039;:script.:suffix&#039;);
        $this-&gt;_inflector-&gt;setStaticRuleReference(&#039;suffix&#039;, $this-&gt;_suffix);
    }

    /**
     * Set suffix; updates suffix static rule in inflector
     *
     * @param  string $suffix
     * @return Foo
     */
    public function setSuffix($suffix)
    {
        $this-&gt;_suffix = $suffix;
        return $this;
    }
}
</pre>

        </div>

        <div class="section" id="zend.filter.inflector.rules.filters"><div class="info"><h1 class="title">Filter Inflector Rules</h1></div>
            

            <p class="para">
                <span class="classname">Zend_Filter</span> filters may be used as inflector rules
                as well. Just like static rules, these are bound to a target
                variable; unlike static rules, you may define multiple filters
                to use when inflecting. These filters are processed in order, so
                be careful to register them in an order that makes sense for the
                data you receive.
            </p>

            <p class="para">
                Rules may be added using  <span class="methodname">setFilterRule()</span> (which
                overwrites any previous rules for that variable) or
                 <span class="methodname">addFilterRule()</span> (which appends the new rule to any
                existing rule for that variable). Filters are specified in one
                of the following ways:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <em class="emphasis">String</em>. The string may be a filter
                        class name, or a class name segment minus any prefix set
                        in the inflector&#039;s plugin loader (by default, minus the
                        &#039;<span class="classname">Zend_Filter</span>&#039; prefix).
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <em class="emphasis">Filter object</em>. Any object instance
                        implementing <span class="classname">Zend_Filter_Interface</span> may be
                        passed as a filter.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <em class="emphasis">Array</em>. An array of one or more
                        strings or filter objects as defined above.
                    </p>
                </li>
            </ul>

            <pre class="programlisting brush: php">
$inflector = new Zend_Filter_Inflector(&#039;:script.:suffix&#039;);

// Set rule to use Zend_Filter_Word_CamelCaseToDash filter
$inflector-&gt;setFilterRule(&#039;script&#039;, &#039;Word_CamelCaseToDash&#039;);

// Add rule to lowercase string
$inflector-&gt;addFilterRule(&#039;script&#039;, new Zend_Filter_StringToLower());

// Set rules en-masse
$inflector-&gt;setFilterRule(&#039;script&#039;, array(
    &#039;Word_CamelCaseToDash&#039;,
    new Zend_Filter_StringToLower()
));
</pre>

        </div>

        <div class="section" id="zend.filter.inflector.rules.multiple"><div class="info"><h1 class="title">Setting Many Rules At Once</h1></div>
            

            <p class="para">
                Typically, it&#039;s easier to set many rules at once than to
                configure a single variable and its inflection rules at a time.
                <span class="classname">Zend_Filter_Inflector</span>&#039;s  <span class="methodname">addRules()</span>
                and  <span class="methodname">setRules()</span> method allow this.
            </p>

            <p class="para">
                Each method takes an array of variable and rule pairs, where the
                rule may be whatever the type of rule accepts (string, filter
                object, or array). Variable names accept a special notation to
                allow setting static rules and filter rules, according to the
                following notation:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <em class="emphasis">&#039;:&#039; prefix</em>: filter rules.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <em class="emphasis">No prefix</em>: static rule.
                    </p>
                </li>
            </ul>

            <div class="example" id="zend.filter.inflector.rules.multiple.example"><div class="info"><p><b>Example #2 Setting Multiple Rules at Once</b></p></div>
                

                <pre class="programlisting brush: php">
// Could also use setRules() with this notation:
$inflector-&gt;addRules(array(
    // filter rules:
    &#039;:controller&#039; =&gt; array(&#039;CamelCaseToUnderscore&#039;,&#039;StringToLower&#039;),
    &#039;:action&#039;     =&gt; array(&#039;CamelCaseToUnderscore&#039;,&#039;StringToLower&#039;),

    // Static rule:
    &#039;suffix&#039;      =&gt; &#039;phtml&#039;
));
</pre>

            </div>
        </div>
    </div>

    <div class="section" id="zend.filter.inflector.utility"><div class="info"><h1 class="title">Utility Methods</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Filter_Inflector</span> has a number of utility methods
            for retrieving and setting the plugin loader, manipulating and
            retrieving rules, and controlling if and when exceptions are thrown.
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                     <span class="methodname">setPluginLoader()</span> can be used when you have
                    configured your own plugin loader and wish to use it with
                    <span class="classname">Zend_Filter_Inflector</span>;
                     <span class="methodname">getPluginLoader()</span> retrieves the currently set
                    one.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">setThrowTargetExceptionsOn()</span> can be used to
                    control whether or not  <span class="methodname">filter()</span> throws an
                    exception when a given replacement identifier passed to it
                    is not found in the target. By default, no exceptions are
                    thrown.  <span class="methodname">isThrowTargetExceptionsOn()</span> will tell
                    you what the current value is.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getRules($spec = null)</span> can be used to retrieve all
                    registered rules for all variables, or just the rules for a
                    single variable.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getRule($spec, $index)</span> fetches a single rule
                    for a given variable; this can be useful for fetching a
                    specific filter rule for a variable that has a filter chain.
                    <var class="varname">$index</var> must be passed.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">clearRules()</span> will clear all currently
                    registered rules.
                </p>
            </li>
        </ul>
    </div>

    <div class="section" id="zend.filter.inflector.config"><div class="info"><h1 class="title">Using Zend_Config with Zend_Filter_Inflector</h1></div>
        

        <p class="para">
            You can use <span class="classname">Zend_Config</span> to set rules, filter prefix
            paths, and other object state in your inflectors, either by passing
            a <span class="classname">Zend_Config</span> object to the constructor or
             <span class="methodname">setOptions()</span>. The following settings may be specified:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <span class="property">target</span> specifies the inflection target.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <span class="property">filterPrefixPath</span> specifies one or more filter
                    prefix and path pairs for use with the inflector.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <span class="property">throwTargetExceptionsOn</span> should be a boolean
                    indicating whether or not to throw exceptions when a
                    replacement identifier is still present after inflection.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <span class="property">targetReplacementIdentifier</span> specifies the
                    character to use when identifying replacement variables in
                    the target string.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <span class="property">rules</span> specifies an array of inflection rules;
                    it should consist of keys that specify either values or
                    arrays of values, consistent with  <span class="methodname">addRules()</span>.
                </p>
            </li>
        </ul>

        <div class="example" id="zend.filter.inflector.config.example"><div class="info"><p><b>Example #3 Using Zend_Config with Zend_Filter_Inflector</b></p></div>
            

            <pre class="programlisting brush: php">
// With the constructor:
$config    = new Zend_Config($options);
$inflector = new Zend_Filter_Inflector($config);

// Or with setOptions():
$inflector = new Zend_Filter_Inflector();
$inflector-&gt;setOptions($config);
</pre>

        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.filter.input.html">Zend_Filter_Input</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.filter.html">Zend_Filter</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.form.html">Zend_Form</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.filter.html">Zend_Filter</a></li>
  <li><a href="zend.filter.introduction.html">Introduction</a></li>
  <li><a href="zend.filter.set.html">Standard Filter Classes</a></li>
  <li><a href="zend.filter.filter_chains.html">Filter Chains</a></li>
  <li><a href="zend.filter.writing_filters.html">Writing Filters</a></li>
  <li><a href="zend.filter.input.html">Zend_Filter_Input</a></li>
  <li class="active"><a href="zend.filter.inflector.html">Zend_Filter_Inflector</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>